package com.qunar.qcf.core.service;

import com.qunar.qcf.core.session.IoSession;

/**
 * An internal interface to represent an 'I/O processor' that performs
 * actual I/O operations for {@link IoSession}s.  It abstracts existing
 * reactor frameworks such as Java NIO once again to simplify transport
 * implementations.
 *
 * @param <S> the type of the {@link IoSession} this processor can handle
 * 
 * 操作IO会话的接口,对现有的Reactor模式架构的Java NIO框架继续做了一层封装
 * 泛形参数指明了它能处理的会话类型
 */
public interface IoProcessor<S extends IoSession> {

    /**
     * Returns <tt>true</tt> if and if only {@link #dispose()} method has
     * been called.  Please note that this method will return <tt>true</tt>
     * even after all the related resources are released.
     */
    boolean isDisposing();
    
    /**
     * Returns <tt>true</tt> if and if only all resources of this processor
     * have been disposed.
     */
    boolean isDisposed();
    
    /**
     * Releases any resources allocated by this processor.  Please note that 
     * the resources might not be released as long as there are any sessions
     * managed by this processor.  Most implementations will close all sessions
     * immediately and release the related resources.
     */
    void dispose();
    
    /**
     * Adds the specified {@code session} to the I/O processor so that
     * the I/O processor starts to perform any I/O operations related
     * with the {@code session}.
     * 将指定会话加入到此Processor中
     */
    void add(S session);

    /**
     * Flushes the internal write request queue of the specified
     * {@code session}.
     * 写操作会有一个写请求队列，flush就用于对指定会话的写请求队列进行强制刷数据
     */
    void flush(S session);

    /**
     * Controls the traffic of the specified {@code session} depending of the
     * {@link IoSession#isReadSuspended()} and {@link IoSession#isWriteSuspended()}
     * flags
     * 制会话的I/O行为，比如是否允许读/写
     */
    void updateTrafficControl(S session);

    /**
     * Removes and closes the specified {@code session} from the I/O
     * processor so that the I/O processor closes the connection
     * associated with the {@code session} and releases any other related
     * resources.
     * 从此Processor中移除和关闭指定会话，这样就可以关闭会话相关联的连接并释放所有相关资源
     */
    void remove(S session);
}
